MUSIC/SP Kermit 4.2.n Installation Instructions
                     (1993 June)
 
Get the necessary files from the Kermit distribution tape or from BITNET
KERMSRV or elsewhere.  Note that many of the files are generic for
Kermit-370 and may already be available from a local CMS or TSO site.  As
distributed by Columbia, the files are named as follows, all with prefix
IKM or IK0 (I K Zero):
 
   IKMGUP.ASM  Assembler source for MUSIC-specific part of GUPI
   IKMKER.BWR  A "beware" file, listing known bugs and problems
   IKMKER.DOC  MUSIC Kermit User Guide, plain text
   IKMKER.HLP  Kermit-MUSIC short help file
   IKMKER.INS  Kermit-MUSIC installation instructions (this file)
   IKMKER.UPD  Updates for MUSIC version of Kermit-370
   IKMMAC.ASM  Assembler source for MUSIC-specific macros
   IKMUTL.ASM  Assembler source for MUSIC-specific routines
   IK0CMD.ASM  Assembler source for command handler
   IK0COM.ASM  Assembler source for global code
   IK0DEF.ASM  Assembler source for parameter definitions
   IK0DOC.ASM  Assembler source with brief history
   IK0GUP.ASM  Assembler source for generic update program GUPI
   IK0KAN.ASM  Assembler source for Kanji character translation
   IK0MAC.ASM  Assembler source for generic Kermit macros
   IK0MAI.ASM  Assembler source for storage initialization
   IK0PRO.ASM  Assembler source for generic routines
 
The following files are not necessary for installation, but may be of
some interest.
 
   IKCACT.ASM  Assembler source for optional accounting exit routine
   IKMHDR.MSS  Scribe source for producing IKMKER.DOC
   IKMKER.ANN  Text of Kermit-MUSIC 4.2 announcement
   IKMKER.LPT  Line-printer (paginated) equivalent of IKMKER.DOC
   IKMKER.MSS  Scribe source for MUSIC part of IKMKER.DOC
   IKMKER.PS   PostScript equivalent of IKMKER.DOC
   IK0AAA.HLP  Implementation notes for 4.2
   IK0CON.HLP  Notes on supporting other terminal controllers
   IK0KER.ANN  Text of generic Kermit-370 4.2 announcement
   IK0KER.MSS  Scribe source for generic part of IKMKER.DOC
   IK0KER.UPD  Update history for Kermit-370
   IK0POR.HLP  Notes on porting Kermit-370 to other systems
   IK0VER.FOR  Comparison program for generating update decks
 
Kermit-MUSIC installation consists at present of a few small jobs that
(a) build GUPI (Generic Update Program), (b) use GUPI to apply the
current fixes to the base code, and (c) assemble and link the updated
Kermit source.  The source for Kermit and GUPI itself is in many pieces,
some generic for Kermit-370 and some specific to MUSIC.  All the
necessary pieces are sequenced in columns 73-80 so that the numbers form
a strictly increasing sequence when the pieces are correctly "pasted"
together.  It is important to preserve the original sequence numbers so
that updates, if any, can be applied to the source.
 
The following jobstreams assume that all source modules are stored under
the code $KRM.  It also assumes that the source files have an extension
of .S as opposed to .ASM.
 
To create a runnable version:
 
1. Collect the following "ASM" files from the Kermit distribution onto
   the code $KRM with RECFM FC and LRECL 80: IK0DOC, IK0MAC, IKMMAC,
   IK0DEF, IK0MAI, IK0COM, IK0CMD, IKMUTL, IK0KAN, IK0PRO, IK0GUP, and
   IKMGUP.  The files must have an extension of ".S".  Therefore, the
   files should be called:
 
              $KRM:IK0DOC.S
              $KRM:IK0MAC.S
              $KRM:IKMMAC.S
              $KRM:IK0DEF.S
              $KRM:IK0MAI.S
              $KRM:IK0COM.S
              $KRM:IK0CMD.S
              $KRM:IKMUTL.S
              $KRM:IK0KAN.S
              $KRM:IK0PRO.S
              $KRM:IK0GUP.S
              $KRM:IKMGUP.S
 
2. Assemble the Generic Update Program GUPI.  This program is required
   to apply the base mods to the Kermit-MUSIC source.  Before assembling
   the GUPI program, you must change the IK0GUP module.  Edit the file
   $KRM:IK0GUP.S and convert all COPY pseudo-instructions into macro
   invocations.  This is easily achieved by removing the word "COPY"
   from in front of the copy block's name.  There are only 5 occurences
   of this and they are all in column 10.  The source for GUPI consists
   of the combination IK0MAC, IKMMAC, IKMGUP, and IK0GUP.  The following
   jobstream can be used to assemble the GUPI module.
 
      /FILE SYSPUNCH N($KRM:GUPI.OBJ) NEW(REPL)
      /FILE SYSLIB PDS($MCM:*.M,$MCU:*.M) DEF
      /FILE SYSUT1 N(&&TEMP) NEW DELETE RECFM(V) SP(300) DEF
      /FILE SYSUT2 N(&&TEMP) NEW DELETE RECFM(V) SP(300) DEF
      /FILE SYSUT3 N(&&TEMP) NEW DELETE RECFM(V) SP(300) DEF
      /SYS TIME=MAX
      /LOAD ASM
      /JOB NOGO
      /OPT XREF,DECK
      /INC $KRM:IK0MAC.S
      /INC $KRM:IKMMAC.S
      /INC $KRM:IKMGUP.S
      /INC $KRM:IK0GUP.S
 
3. Link the object deck created by the previous step, producing
   $KRM:GUPI.LMOD.  The following jobstream will do this.
 
      /FILE LMOD N($KRM:GUPI.LMOD) NEW(REPL) RECFM(F) LRECL(80)
      /LOAD LKED
      /JOB MAP,NOGO,PRINT,STATS,NAME=GUPI,MODE=OS
      .ORG 4A00
      /INC $KRM:GUPI.OBJ
 
4. Create the GUPI program file from the following JCL.
 
      /SYS NOPRINT,REGION=1024
      /FILE LMOD N($KRM:GUPI.LMOD)
      /LOAD XMON
      GUPI
 
5. Build the base Kermit source so that you can apply modifications over
   it.  Merge the source files in the order IK0DOC, IK0MAC, IKMMAC,
   IK0DEF, IK0MAI, IK0COM, IK0CMD, IKMUTL, IK0PRO, and save the result
   as $KRM:KERMIT.BASE.S. You will have to enlarge the editor workfile
   to 15000 records. Make a local copy of the EDITOR file and change
   the NREC parameter for the workfile from 6000 to 15000.
 
   IK0KAN.S is optional.  Including it adds about 32 Kbytes to the
   Kermit program.
 
      /PARM NEW
      /INC EDITOR
      MERGE $KRM:IK0DOC.S
      MERGE $KRM:IK0MAC.S
      MERGE $KRM:IKMMAC.S
      MERGE $KRM:IK0DEF.S
      MERGE $KRM:IK0MAI.S
      MERGE $KRM:IK0COM.S
      MERGE $KRM:IK0CMD.S
      MERGE $KRM:IKMUTL.S
      MERGE $KRM:IK0KAN.S
      MERGE $KRM:IK0PRO.S
      PURGE $KRM:KERMIT.BASE.S
      FILE $KRM:KERMIT.BASE.S
 
6. Apply the updates using GUPI.  Note: this operation requires a region
   of at least 1024K.  The following command will apply the fixes to the
   source module $KRM:KERMIT.BASE.S using the update file
   $KRM:IKMKER.UPD and save the updated source in $KRM:KERMIT.S.
 
          GUPI $KRM:KERMIT.BASE.S $KRM:IKMKER.UPD $KRM:KERMIT.S
 
7. Assemble the Kermit source with the following jobstream.
 
      /FILE SYSPUNCH N($KRM:KERMIT.OBJ) NEW(REPL)
      /FILE SYSLIB PDS($MCM:*.M,$MCU:*.M) DEF
      /FILE SYSUT1 N(&&TEMP) NEW DELETE RECFM(V) SP(300) DEF
      /FILE SYSUT2 N(&&TEMP) NEW DELETE RECFM(V) SP(300) DEF
      /FILE SYSUT3 N(&&TEMP) NEW DELETE RECFM(V) SP(300) DEF
      /SYS TIME=MAX
      /LOAD ASM
      /JOB NOGO
      /OPT XREF,DECK
      /INC $KRM:KERMIT.S
 
8. Link the object deck created by the previous step together with
   MATCH and MFINDX to produce $KRM:KERMIT.LMOD.
 
      /FILE LMOD N($KRM:KERMIT.LMOD) NEW(REPL) RECFM(F) LRECL(128) SHR
      /LOAD LKED
      /JOB MAP,NOGO,PRINT,STATS,NAME=KERMIT,MODE=OS
      .ORG 4A00
      /INC $KRM:KERMIT.OBJ
      /INC $SUB:MATCH.OBJ
      /INC $SUB:MFINDX.OBJ
 
9. Save the following jobstream in the file $KRM:KERMIT.  This will
   execute the KERMIT program with the proper system parameters.
   The file MUST be saved as a PUBL,XO file so that the program
   privileges are assigned properly by the system.
 
        /SYS NOPRINT,REGION=256
        /FILE LMOD N($KRM:KERMIT.LMOD) SHR
        /LOAD XMON
        KERMIT
 
10. Kermit-MUSIC requries the LSCAN privilege since it does a save
    library scan directly.  You must modify either the system module
    LOOKUP or the macro invoked by LOOKUP called $MCM:USERTBL.M.  Add
    the line
 
          FILNAM '$KRM:KERMIT',(LSCAN,0)
 
    to either of the two files.  Reassemble the module LOOKUP and make
    sure that the new object deck is used to when rebuilding the
    nucleus.  If you do not give Kermit this privilege, the program will
    abend on user codes that do not have LSCAN.
 
11. Copy the file IKMKER.HLP to the MUSIC file $KRM:SYSTEM.KERMHELP
    and save it as a PUBLIC file. This file is displayed when the
    HELP subcommand is issued to Kermit-MUSIC.
 
                    * * Accounting Routine * *
 
If you wish to use the optional accounting exit routine with Kermit,
you must create the object for it (using a procedure similar to step 7)
and load it explicitly with Kermit (by adding another /INC to step 8).
The sample currently available was written for CMS and must be adapted
to run under MUSIC.  Any user who does so is urged to contribute the
MUSIC version for inclusion in the Kermit distribution under the name
IKMACT.ASM.  Even when such a MUSIC-specific sample is available, you
should examine the source and customize it to your installation's needs
before using it.
 
                       * * Configuration * *
 
The IBM mainframe and its communications front end (3705, 7171, etc.)
usually require that parity be used by any asynchronous ASCII device
that wishes to communicate with it.  Exactly which kind of parity is
site-dependent.  At Columbia, the 3705 requires Mark parity, and the
7171 requires Even parity.  Make sure your users know to use the
appropriate parity setting, as well as any other settings required for
IBM mainframe communication (see p.36-39 of the Kermit book).
 
For linemode transfers, the ASCII/EBCDIC translation in the front end is
a key factor.  Kermit-MUSIC uses an ASCII/EBCDIC translation table which
conforms to the one given in the IBM System/370 Reference Summary.  If
your site's translation table is incompatible with the one Kermit uses,
then enter the appropriate SET ATOE/ETOA/TATOE/TETOA subcommands in the
SYSTEM KERMINI file.  As long as the system tables are invertible with
respect to the printable ASCII characters (even if the A-to-E and E-to-A
tables are not the inverses of each other), the SET subcommands can
compensate.  However, if your system's ASCII/EBCDIC tables are not
invertible, Kermit will not and cannot work; you must change your
system's tables.  Refer to the generic Kermit-370 chapter of the User's
Guide for a step-by-step customization procedure (see the section on
translation tables).
 
Kermit-MUSIC operation is possible for many types of protocol converters;
it requires only that the converter have some kind of transparent mode.
Be sure the converter is configured so that the graphics or transparent
mode, whatever it is called, is enabled.  See IK0AAA.HLP for a list of
front ends that are known to work and for a collection of notes and
special warnings about some of them.  Some further installation details
follow for specific devices.
 
When MUSIC Kermit is to be used with a 7171, make sure the 7171 is set up
with its "keyboard lock delay" parameter set to 0.  Otherwise, the
"terminal" will hang whenever MUSIC Kermit clears the screen.  This
happens consistently when the parameter is set to 10, and not at all
when set to 0.  For numbers in between, the higher the number, the more
it happens.
 
There is another problem in the 7171 that can cause Kermit file
transfers to abort after a flurry of retransmissions if XON/XOFF flow
control is used by the receiving Kermit, or even by hardware in between
the 7171 and the receiver.  To prevent this problem, set the 7171 flags
so that XOFF is not a valid terminator of a transparent read.  See page
4-20 of "IBM 7171 Reference Manual and Programming Guide" (IBM
publication number GA27-0021).
 
Kermit operation through a Renex protocol converter generally requires
that type-ahead be turned off.
 
Kermit operation is possible through an IBM 3708 front end in two
different configurations.  In the first, the terminal line must be set
for either "protocol enveloping" or "dynamic" mode, and a session must
be set for line-at-a-time operation for Kermit to work.  Other important
details of the terminal configuration are: (1) the terminal must be
specified as a TWX device, (2) the SSCP format should be set to USSNTO,
(3) the terminal type ID should be set to 05, (4) the line should be set
for 8, or possibly 7, data bits and 1 stop bit, (5) there should be no
"read prompt", and (6) the so-called "alternate" translation table
(number 3) should be selected.  Kermit-MUSIC may also need to be
configured because some models of the 3708 (or some environments) do not
pass the normal packet character SOH (code 1, CTRL-A).  A suitable
substitute is HT (code 9, CTRL-I).  Alternatively, or additionally, it
may help to set the 3708 "interface type" to 0.
 
The second possible 3708 configuration is "protocol conversion" mode and
makes use of the FULLSCREEN type in Kermit, which is also suitable for
many other kinds of protocol converter.  The basic setup consists of the
following Kermit subcommands.
 
     .... mainframe .....        ....... PC .........
     SET CONTROLLER FULL         set send start 62
     SET RECEIVE START 62        set receive start 62
     SET SEND START 62           set block b
     SET BLOCK B                 set handshake none
     SET HANDSHAKE 0
 
The 62's (Greater-than sign) may be replaced by some other decimal code
for a printable character.  For best results, choose a character that
seldom appears in the files you will be transferring.  In particular,
avoid the Control, Eighth-bit, and Repeat prefixes.  Packet sizes are
automatically restricted by Kermit-MUSIC, so you needn't set them unless
conditions require packets shorter than the default (77).  Flow control
may be needed to keep up with the data rate on some equipment.  The
block check type should be set to "B" only if the protocol converter is
overzealous in optimizing the data stream -- there are hazards in using
any type other than "1" because of all the packet echoing.  Refer to
IK0AAA.HLP for such details.  Note that the translation of characters
imposes the same setup requirements on FULLSCREEN mode as on the
traditional TTY mode (linemode).  See the DOC.
 
Kermit-MUSIC supports file transfers through the IBM 3174 AEA with B2
microcode, but support is restricted to terminals with the ASCII
Graphics capability in three ways that may require compensating
installation:
 
a) The terminal type must be defined in the 3174 to support graphics
   (only the built-in VT241 and Tektronix 4205 types plus suitable
   user-defined terminal types).  IBM's AEA Reference describes how
   to set up terminal tables.
 
b) The line must be defined without a Host Addressable Printer.
 
c) If the 3174 is owned by VTAM, the connection must be made with a
   logmode that allows the Read Partition Query (such as M2SDLCQ).
